home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpunit.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  15.9 KB  |  386 lines
  1. <refentry id="libgimp-gimpunit" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimpunit</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimpunit</refname><refpurpose>Provides a collection of predefined units and functions for creating
  10. user-defined units.</refpurpose>
  11. </refnamediv>
  12.  
  13. <refsynopsisdiv><title>Synopsis</title>
  14. <synopsis>
  15.  
  16.  
  17.  
  18. enum        <link linkend="GimpUnit">GimpUnit</link>;
  19. <link linkend="gint">gint</link>        <link linkend="gimp-unit-get-number-of-units">gimp_unit_get_number_of_units</link>   (void);
  20. <link linkend="gint">gint</link>        <link linkend="gimp-unit-get-number-of-built-in-units">gimp_unit_get_number_of_built_in_units</link>
  21.                                             (void);
  22. <link linkend="GimpUnit">GimpUnit</link>    <link linkend="gimp-unit-new">gimp_unit_new</link>                   (<link linkend="gchar">gchar</link> *identifier,
  23.                                              <link linkend="gdouble">gdouble</link> factor,
  24.                                              <link linkend="gint">gint</link> digits,
  25.                                              <link linkend="gchar">gchar</link> *symbol,
  26.                                              <link linkend="gchar">gchar</link> *abbreviation,
  27.                                              <link linkend="gchar">gchar</link> *singular,
  28.                                              <link linkend="gchar">gchar</link> *plural);
  29. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-unit-get-deletion-flag">gimp_unit_get_deletion_flag</link>     (<link linkend="GimpUnit">GimpUnit</link> unit);
  30. void        <link linkend="gimp-unit-set-deletion-flag">gimp_unit_set_deletion_flag</link>     (<link linkend="GimpUnit">GimpUnit</link> unit,
  31.                                              <link linkend="gboolean">gboolean</link> deletion_flag);
  32. <link linkend="gdouble">gdouble</link>     <link linkend="gimp-unit-get-factor">gimp_unit_get_factor</link>            (<link linkend="GimpUnit">GimpUnit</link> unit);
  33. <link linkend="gint">gint</link>        <link linkend="gimp-unit-get-digits">gimp_unit_get_digits</link>            (<link linkend="GimpUnit">GimpUnit</link> unit);
  34. <link linkend="gchar">gchar</link>*      <link linkend="gimp-unit-get-identifier">gimp_unit_get_identifier</link>        (<link linkend="GimpUnit">GimpUnit</link> unit);
  35. <link linkend="gchar">gchar</link>*      <link linkend="gimp-unit-get-symbol">gimp_unit_get_symbol</link>            (<link linkend="GimpUnit">GimpUnit</link> unit);
  36. <link linkend="gchar">gchar</link>*      <link linkend="gimp-unit-get-abbreviation">gimp_unit_get_abbreviation</link>      (<link linkend="GimpUnit">GimpUnit</link> unit);
  37. <link linkend="gchar">gchar</link>*      <link linkend="gimp-unit-get-singular">gimp_unit_get_singular</link>          (<link linkend="GimpUnit">GimpUnit</link> unit);
  38. <link linkend="gchar">gchar</link>*      <link linkend="gimp-unit-get-plural">gimp_unit_get_plural</link>            (<link linkend="GimpUnit">GimpUnit</link> unit);
  39. </synopsis>
  40. </refsynopsisdiv>
  41.  
  42.  
  43.  
  44.  
  45.  
  46. <refsect1>
  47. <title>Description</title>
  48. <para>
  49. Provides a collection of predefined units and functions for creating
  50. user-defined units.
  51.  
  52. </para>
  53. </refsect1>
  54.  
  55. <refsect1>
  56. <title>Details</title>
  57. <refsect2>
  58. <title><anchor id="GimpUnit">enum GimpUnit</title>
  59. <programlisting>typedef enum
  60. {
  61.   GIMP_UNIT_PIXEL   = 0,
  62.  
  63.   GIMP_UNIT_INCH    = 1,
  64.   GIMP_UNIT_MM      = 2,
  65.   GIMP_UNIT_POINT   = 3,
  66.   GIMP_UNIT_PICA    = 4,
  67.  
  68.   GIMP_UNIT_END     = 5,
  69.  
  70.   GIMP_UNIT_PERCENT = 65536
  71. } GimpUnit;
  72. </programlisting>
  73. <para>
  74.  
  75. </para></refsect2>
  76. <refsect2>
  77. <title><anchor id="gimp-unit-get-number-of-units">gimp_unit_get_number_of_units ()</title>
  78. <programlisting><link linkend="gint">gint</link>        gimp_unit_get_number_of_units   (void);</programlisting>
  79. <para>
  80. Returns the number of units which are known to the <link linkend="GimpUnit">GimpUnit</link> system.</para>
  81. <para>
  82.  
  83. </para><informaltable pgwide=1 frame="none" role="params">
  84. <tgroup cols="2">
  85. <colspec colwidth="2*">
  86. <colspec colwidth="8*">
  87. <tbody>
  88. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The number of defined units.
  89.  
  90. </entry></row>
  91. </tbody></tgroup></informaltable></refsect2>
  92. <refsect2>
  93. <title><anchor id="gimp-unit-get-number-of-built-in-units">gimp_unit_get_number_of_built_in_units ()</title>
  94. <programlisting><link linkend="gint">gint</link>        gimp_unit_get_number_of_built_in_units
  95.                                             (void);</programlisting>
  96. <para>
  97. Returns the number of <link linkend="GimpUnit">GimpUnit</link>'s which are hardcoded in the unit system
  98. (UNIT_INCH, UNIT_MM, UNIT_POINT, UNIT_PICA and the two "pseudo unit"
  99. UNIT_PIXEL).</para>
  100. <para>
  101.  
  102. </para><informaltable pgwide=1 frame="none" role="params">
  103. <tgroup cols="2">
  104. <colspec colwidth="2*">
  105. <colspec colwidth="8*">
  106. <tbody>
  107. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The number of built-in units.
  108.  
  109. </entry></row>
  110. </tbody></tgroup></informaltable></refsect2>
  111. <refsect2>
  112. <title><anchor id="gimp-unit-new">gimp_unit_new ()</title>
  113. <programlisting><link linkend="GimpUnit">GimpUnit</link>    gimp_unit_new                   (<link linkend="gchar">gchar</link> *identifier,
  114.                                              <link linkend="gdouble">gdouble</link> factor,
  115.                                              <link linkend="gint">gint</link> digits,
  116.                                              <link linkend="gchar">gchar</link> *symbol,
  117.                                              <link linkend="gchar">gchar</link> *abbreviation,
  118.                                              <link linkend="gchar">gchar</link> *singular,
  119.                                              <link linkend="gchar">gchar</link> *plural);</programlisting>
  120. <para>
  121. Returns the integer ID of the new <link linkend="GimpUnit">GimpUnit</link>.
  122. </para>
  123. <para>
  124. Note that a new unit is always created with it's deletion flag
  125. set to <link linkend="TRUE-CAPS">TRUE</link>. You will have to set it to <link linkend="FALSE-CAPS">FALSE</link> with
  126. <link linkend="gimp-unit-set-deletion-flag">gimp_unit_set_deletion_flag</link>() to make the unit definition persistent.</para>
  127. <para>
  128.  
  129. </para><informaltable pgwide=1 frame="none" role="params">
  130. <tgroup cols="2">
  131. <colspec colwidth="2*">
  132. <colspec colwidth="8*">
  133. <tbody>
  134. <row><entry align="right"><parameter>identifier</parameter> :</entry>
  135. <entry> The unit's identifier string.
  136. </entry></row>
  137. <row><entry align="right"><parameter>factor</parameter> :</entry>
  138. <entry> The unit's factor (how many units are in one inch).
  139. </entry></row>
  140. <row><entry align="right"><parameter>digits</parameter> :</entry>
  141. <entry> The unit's suggested number of digits (see <link linkend="gimp-unit-get-digits">gimp_unit_get_digits</link>()).
  142. </entry></row>
  143. <row><entry align="right"><parameter>symbol</parameter> :</entry>
  144. <entry> The symbol of the unit (e.g. "''" for inch).
  145. </entry></row>
  146. <row><entry align="right"><parameter>abbreviation</parameter> :</entry>
  147. <entry> The abbreviation of the unit.
  148. </entry></row>
  149. <row><entry align="right"><parameter>singular</parameter> :</entry>
  150. <entry> The singular form of the unit.
  151. </entry></row>
  152. <row><entry align="right"><parameter>plural</parameter> :</entry>
  153. <entry> The plural form of the unit.
  154. </entry></row>
  155. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The ID of the new unit.
  156.  
  157. </entry></row>
  158. </tbody></tgroup></informaltable></refsect2>
  159. <refsect2>
  160. <title><anchor id="gimp-unit-get-deletion-flag">gimp_unit_get_deletion_flag ()</title>
  161. <programlisting><link linkend="gboolean">gboolean</link>    gimp_unit_get_deletion_flag     (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  162. <para>
  163. </para>
  164. <para>
  165.  
  166. </para><informaltable pgwide=1 frame="none" role="params">
  167. <tgroup cols="2">
  168. <colspec colwidth="2*">
  169. <colspec colwidth="8*">
  170. <tbody>
  171. <row><entry align="right"><parameter>unit</parameter> :</entry>
  172. <entry> The unit you want to know the <parameter>deletion_flag</parameter> of.
  173. </entry></row>
  174. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit's <parameter>deletion_flag</parameter>.
  175.  
  176. </entry></row>
  177. </tbody></tgroup></informaltable></refsect2>
  178. <refsect2>
  179. <title><anchor id="gimp-unit-set-deletion-flag">gimp_unit_set_deletion_flag ()</title>
  180. <programlisting>void        gimp_unit_set_deletion_flag     (<link linkend="GimpUnit">GimpUnit</link> unit,
  181.                                              <link linkend="gboolean">gboolean</link> deletion_flag);</programlisting>
  182. <para>
  183. Sets a <link linkend="GimpUnit">GimpUnit</link>'s <parameter>deletion_flag</parameter>. If the <parameter>deletion_flag</parameter> of a unit is
  184. <link linkend="TRUE-CAPS">TRUE</link> when GIMP exits, this unit will not be saved in the uses's
  185. "unitrc" file.
  186. </para>
  187. <para>
  188. Trying to change the <parameter>deletion_flag</parameter> of a built-in unit will be silently
  189. ignored.</para>
  190. <para>
  191.  
  192. </para><informaltable pgwide=1 frame="none" role="params">
  193. <tgroup cols="2">
  194. <colspec colwidth="2*">
  195. <colspec colwidth="8*">
  196. <tbody>
  197. <row><entry align="right"><parameter>unit</parameter> :</entry>
  198. <entry> The unit you want to set the <parameter>deletion_flag</parameter> for.
  199. </entry></row>
  200. <row><entry align="right"><parameter>deletion_flag</parameter> :</entry>
  201. <entry> The new deletion_flag.
  202. </entry></row>
  203. </tbody></tgroup></informaltable></refsect2>
  204. <refsect2>
  205. <title><anchor id="gimp-unit-get-factor">gimp_unit_get_factor ()</title>
  206. <programlisting><link linkend="gdouble">gdouble</link>     gimp_unit_get_factor            (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  207. <para>
  208. A <link linkend="GimpUnit">GimpUnit</link>'s <parameter>factor</parameter> is defined to be:
  209. </para>
  210. <para>
  211. distance_in_units == (<parameter>factor</parameter> * distance_in_inches)
  212. </para>
  213. <para>
  214. Returns 0 for <parameter>unit</parameter> == GIMP_UNIT_PIXEL.</para>
  215. <para>
  216.  
  217. </para><informaltable pgwide=1 frame="none" role="params">
  218. <tgroup cols="2">
  219. <colspec colwidth="2*">
  220. <colspec colwidth="8*">
  221. <tbody>
  222. <row><entry align="right"><parameter>unit</parameter> :</entry>
  223. <entry> The unit you want to know the factor of.
  224. </entry></row>
  225. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit's factor.
  226.  
  227. </entry></row>
  228. </tbody></tgroup></informaltable></refsect2>
  229. <refsect2>
  230. <title><anchor id="gimp-unit-get-digits">gimp_unit_get_digits ()</title>
  231. <programlisting><link linkend="gint">gint</link>        gimp_unit_get_digits            (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  232. <para>
  233. Returns the number of digits an entry field should provide to get
  234. approximately the same accuracy as an inch input field with two digits.
  235. </para>
  236. <para>
  237. Returns 0 for <parameter>unit</parameter> == GIMP_UNIT_PIXEL.</para>
  238. <para>
  239.  
  240. </para><informaltable pgwide=1 frame="none" role="params">
  241. <tgroup cols="2">
  242. <colspec colwidth="2*">
  243. <colspec colwidth="8*">
  244. <tbody>
  245. <row><entry align="right"><parameter>unit</parameter> :</entry>
  246. <entry> The unit you want to know the digits.
  247. </entry></row>
  248. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The suggested number of digits.
  249.  
  250. </entry></row>
  251. </tbody></tgroup></informaltable></refsect2>
  252. <refsect2>
  253. <title><anchor id="gimp-unit-get-identifier">gimp_unit_get_identifier ()</title>
  254. <programlisting><link linkend="gchar">gchar</link>*      gimp_unit_get_identifier        (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  255. <para>
  256. This is an unstranslated string.
  257. </para>
  258. <para>
  259. NOTE: This string has to be <link linkend="g-free">g_free</link>()'d by plugins but is a pointer to a
  260. constant string when this function is used from inside the GIMP.</para>
  261. <para>
  262.  
  263. </para><informaltable pgwide=1 frame="none" role="params">
  264. <tgroup cols="2">
  265. <colspec colwidth="2*">
  266. <colspec colwidth="8*">
  267. <tbody>
  268. <row><entry align="right"><parameter>unit</parameter> :</entry>
  269. <entry> The unit you want to know the identifier of.
  270. </entry></row>
  271. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit's identifier.
  272.  
  273. </entry></row>
  274. </tbody></tgroup></informaltable></refsect2>
  275. <refsect2>
  276. <title><anchor id="gimp-unit-get-symbol">gimp_unit_get_symbol ()</title>
  277. <programlisting><link linkend="gchar">gchar</link>*      gimp_unit_get_symbol            (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  278. <para>
  279. This is e.g. "''" for UNIT_INCH.
  280. </para>
  281. <para>
  282. NOTE: This string has to be <link linkend="g-free">g_free</link>()'d by plugins but is a pointer to a
  283. constant string when this function is used from inside the GIMP.</para>
  284. <para>
  285.  
  286. </para><informaltable pgwide=1 frame="none" role="params">
  287. <tgroup cols="2">
  288. <colspec colwidth="2*">
  289. <colspec colwidth="8*">
  290. <tbody>
  291. <row><entry align="right"><parameter>unit</parameter> :</entry>
  292. <entry> The unit you want to know the symbol of.
  293. </entry></row>
  294. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit's symbol.
  295.  
  296. </entry></row>
  297. </tbody></tgroup></informaltable></refsect2>
  298. <refsect2>
  299. <title><anchor id="gimp-unit-get-abbreviation">gimp_unit_get_abbreviation ()</title>
  300. <programlisting><link linkend="gchar">gchar</link>*      gimp_unit_get_abbreviation      (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  301. <para>
  302. For built-in units, this function returns the translated abbreviation
  303. of the unit.
  304. </para>
  305. <para>
  306. NOTE: This string has to be <link linkend="g-free">g_free</link>()'d by plugins but is a pointer to a
  307. constant string when this function is used from inside the GIMP.</para>
  308. <para>
  309.  
  310. </para><informaltable pgwide=1 frame="none" role="params">
  311. <tgroup cols="2">
  312. <colspec colwidth="2*">
  313. <colspec colwidth="8*">
  314. <tbody>
  315. <row><entry align="right"><parameter>unit</parameter> :</entry>
  316. <entry> The unit you want to know the abbreviation of.
  317. </entry></row>
  318. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit's abbreviation.
  319.  
  320. </entry></row>
  321. </tbody></tgroup></informaltable></refsect2>
  322. <refsect2>
  323. <title><anchor id="gimp-unit-get-singular">gimp_unit_get_singular ()</title>
  324. <programlisting><link linkend="gchar">gchar</link>*      gimp_unit_get_singular          (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  325. <para>
  326. For built-in units, this function returns the translated singular form
  327. of the unit's name.
  328. </para>
  329. <para>
  330. NOTE: This string has to be <link linkend="g-free">g_free</link>()'d by plugins but is a pointer to a
  331. constant string when this function is used from inside the GIMP.</para>
  332. <para>
  333.  
  334. </para><informaltable pgwide=1 frame="none" role="params">
  335. <tgroup cols="2">
  336. <colspec colwidth="2*">
  337. <colspec colwidth="8*">
  338. <tbody>
  339. <row><entry align="right"><parameter>unit</parameter> :</entry>
  340. <entry> The unit you want to know the singular form of.
  341. </entry></row>
  342. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit's singular form.
  343.  
  344. </entry></row>
  345. </tbody></tgroup></informaltable></refsect2>
  346. <refsect2>
  347. <title><anchor id="gimp-unit-get-plural">gimp_unit_get_plural ()</title>
  348. <programlisting><link linkend="gchar">gchar</link>*      gimp_unit_get_plural            (<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  349. <para>
  350. For built-in units, this function returns the translated plural form
  351. of the unit's name.
  352. </para>
  353. <para>
  354. NOTE: This string has to be <link linkend="g-free">g_free</link>()'d by plugins but is a pointer to a
  355. constant string when this function is used from inside the GIMP.</para>
  356. <para>
  357.  
  358. </para><informaltable pgwide=1 frame="none" role="params">
  359. <tgroup cols="2">
  360. <colspec colwidth="2*">
  361. <colspec colwidth="8*">
  362. <tbody>
  363. <row><entry align="right"><parameter>unit</parameter> :</entry>
  364. <entry> The unit you want to know the plural form of.
  365. </entry></row>
  366. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit's plural form.
  367.  
  368. </entry></row>
  369. </tbody></tgroup></informaltable></refsect2>
  370.  
  371. </refsect1>
  372.  
  373.  
  374.  
  375. <refsect1>
  376. <title>See Also</title>
  377. <para>
  378. <link linkend="GimpUnitMenu">GimpUnitMenu</link>
  379. </para>
  380. <para>
  381. <link linkend="GimpSizeEntry">GimpSizeEntry</link>
  382. </para>
  383. </refsect1>
  384.  
  385. </refentry>
  386.